<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>GAsyncResult</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<link rel="home" href="index.html" title="GIO Reference Manual">
<link rel="up" href="async.html" title="Asynchronous I/O">
<link rel="prev" href="GCancellable.html" title="GCancellable">
<link rel="next" href="gio-GIOScheduler.html" title="GIOScheduler">
<meta name="generator" content="GTK-Doc V1.17 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
<tr valign="middle">
<td><a accesskey="p" href="GCancellable.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="async.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GIO Reference Manual</th>
<td><a accesskey="n" href="gio-GIOScheduler.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr>
<tr><td colspan="5" class="shortcuts">
<a href="#GAsyncResult.synopsis" class="shortcut">Top</a>
                   | 
                  <a href="#GAsyncResult.description" class="shortcut">Description</a>
                   | 
                  <a href="#GAsyncResult.object-hierarchy" class="shortcut">Object Hierarchy</a>
                   | 
                  <a href="#GAsyncResult.prerequisites" class="shortcut">Prerequisites</a>
                   | 
                  <a href="#GAsyncResult.implementations" class="shortcut">Known Implementations</a>
</td></tr>
</table>
<div class="refentry">
<a name="GAsyncResult"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="GAsyncResult.top_of_page"></a>GAsyncResult</span></h2>
<p>GAsyncResult — Asynchronous Function Results</p>
</td>
<td valign="top" align="right"></td>
</tr></table></div>
<div class="refsynopsisdiv">
<a name="GAsyncResult.synopsis"></a><h2>Synopsis</h2>
<pre class="synopsis">
#include &lt;gio/gio.h&gt;

                    <a class="link" href="GAsyncResult.html#GAsyncResult-struct" title="GAsyncResult">GAsyncResult</a>;
struct              <a class="link" href="GAsyncResult.html#GAsyncResultIface" title="struct GAsyncResultIface">GAsyncResultIface</a>;
<span class="returnvalue">void</span>                (<a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()">*GAsyncReadyCallback</a>)              (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> *source_object</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
<a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="GAsyncResult.html#g-async-result-get-user-data" title="g_async_result_get_user_data ()">g_async_result_get_user_data</a>        (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);
<a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="returnvalue">GObject</span></a> *           <a class="link" href="GAsyncResult.html#g-async-result-get-source-object" title="g_async_result_get_source_object ()">g_async_result_get_source_object</a>    (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);
</pre>
</div>
<div class="refsect1">
<a name="GAsyncResult.object-hierarchy"></a><h2>Object Hierarchy</h2>
<pre class="synopsis">
  GInterface
   +----GAsyncResult
</pre>
</div>
<div class="refsect1">
<a name="GAsyncResult.prerequisites"></a><h2>Prerequisites</h2>
<p>
GAsyncResult requires
 <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>.</p>
</div>
<div class="refsect1">
<a name="GAsyncResult.implementations"></a><h2>Known Implementations</h2>
<p>
GAsyncResult is implemented by
 <a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult">GSimpleAsyncResult</a>.</p>
</div>
<div class="refsect1">
<a name="GAsyncResult.description"></a><h2>Description</h2>
<p>
Provides a base class for implementing asynchronous function results.
</p>
<p>
Asynchronous operations are broken up into two separate operations
which are chained together by a <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a>. To begin
an asynchronous operation, provide a <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> to the
asynchronous function. This callback will be triggered when the
operation has completed, and will be passed a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> instance
filled with the details of the operation's success or failure, the
object the asynchronous function was started for and any error codes
returned. The asynchronous callback function is then expected to call
the corresponding "<code class="function">_finish()</code>" function, passing the object the
function was called for, the <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> instance, and (optionally)
an <em class="parameter"><code>error</code></em> to grab any error conditions that may have occurred.
</p>
<p>
The "<code class="function">_finish()</code>" function for an operation takes the generic result
(of type <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>) and returns the specific result that the
operation in question yields (e.g. a <a class="link" href="GFileEnumerator.html" title="GFileEnumerator"><span class="type">GFileEnumerator</span></a> for a
"enumerate children" operation). If the result or error status of the
operation is not needed, there is no need to call the "<code class="function">_finish()</code>"
function; GIO will take care of cleaning up the result and error
information after the <a class="link" href="GAsyncResult.html#GAsyncReadyCallback" title="GAsyncReadyCallback ()"><span class="type">GAsyncReadyCallback</span></a> returns. Applications may
also take a reference to the <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> and call "<code class="function">_finish()</code>"
later; however, the "<code class="function">_finish()</code>" function may be called at most once.
</p>
<p>
Example of a typical asynchronous operation flow:
</p>
<div class="informalexample">
  <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
    <tbody>
      <tr>
        <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38</pre></td>
        <td class="listing_code"><pre class="programlisting"><span class="type">void</span><span class="normal"> </span><span class="function">_theoretical_frobnitz_async</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Theoretical</span><span class="normal">         </span><span class="symbol">*</span><span class="normal">t</span><span class="symbol">,</span>
<span class="normal">                                  </span><span class="usertype">GCancellable</span><span class="normal">        </span><span class="symbol">*</span><span class="normal">c</span><span class="symbol">,</span>
<span class="normal">                                  </span><span class="usertype">GAsyncReadyCallback</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">cb</span><span class="symbol">,</span>
<span class="normal">                                  </span><span class="usertype">gpointer</span><span class="normal">             u</span><span class="symbol">);</span>

<span class="normal"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean">gboolean</a> </span><span class="function">_theoretical_frobnitz_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">Theoretical</span><span class="normal">   </span><span class="symbol">*</span><span class="normal">t</span><span class="symbol">,</span>
<span class="normal">                                       </span><span class="usertype">GAsyncResult</span><span class="normal">  </span><span class="symbol">*</span><span class="normal">res</span><span class="symbol">,</span>
<span class="normal">                                       </span><span class="usertype">GError</span><span class="normal">       </span><span class="symbol">**</span><span class="normal">e</span><span class="symbol">);</span>

<span class="keyword">static</span><span class="normal"> </span><span class="type">void</span>
<span class="function">frobnitz_result_func</span><span class="normal"> </span><span class="symbol">(</span><span class="usertype">GObject</span><span class="normal">      </span><span class="symbol">*</span><span class="normal">source_object</span><span class="symbol">,</span>
<span class="normal">         </span><span class="usertype">GAsyncResult</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">res</span><span class="symbol">,</span>
<span class="normal">         </span><span class="usertype">gpointer</span><span class="normal">      user_data</span><span class="symbol">)</span>
<span class="cbracket">{</span>
<span class="normal">  </span><span class="usertype">gboolean</span><span class="normal"> success </span><span class="symbol">=</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span>

<span class="normal">  success </span><span class="symbol">=</span><span class="normal"> </span><span class="function">_theoretical_frobnitz_finish</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">source_object</span><span class="symbol">,</span><span class="normal"> res</span><span class="symbol">,</span><span class="normal"> <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>

<span class="normal">  </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">success</span><span class="symbol">)</span>
<span class="normal">    </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-String-Utility-Functions.html#g-printf">g_printf</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Hurray!</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">);</span>
<span class="normal">  </span><span class="keyword">else</span>
<span class="normal">    </span><span class="function"><a href="http://library.gnome.org/devel/glib/unstable/glib-String-Utility-Functions.html#g-printf">g_printf</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Uh oh!</span><span class="specialchar">\n</span><span class="string">"</span><span class="symbol">);</span>

<span class="normal">  </span><span class="comment">/* ... */</span>

<span class="cbracket">}</span>

<span class="type">int</span><span class="normal"> </span><span class="function">main</span><span class="normal"> </span><span class="symbol">(</span><span class="type">int</span><span class="normal"> argc</span><span class="symbol">,</span><span class="normal"> </span><span class="type">void</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">argv</span><span class="symbol">[])</span>
<span class="cbracket">{</span>
<span class="normal">   </span><span class="comment">/* ... */</span>

<span class="normal">   </span><span class="function">_theoretical_frobnitz_async</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">theoretical_data</span><span class="symbol">,</span>
<span class="normal">                                <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">,</span>
<span class="normal">                                frobnitz_result_func</span><span class="symbol">,</span>
<span class="normal">                                <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">);</span>

<span class="normal">   </span><span class="comment">/* ... */</span>
<span class="cbracket">}</span></pre></td>
      </tr>
    </tbody>
  </table>
</div>

<p>
</p>
<p>
The callback for an asynchronous operation is called only once, and is
always called, even in the case of a cancelled operation. On cancellation
the result is a <a class="link" href="gio-GIOError.html#G-IO-ERROR-CANCELLED:CAPS"><code class="literal">G_IO_ERROR_CANCELLED</code></a> error.
</p>
<p>
Some asynchronous operations are implemented using synchronous calls.
These are run in a separate thread, if <a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GThread"><span class="type">GThread</span></a> has been initialized, but
otherwise they are sent to the Main Event Loop and processed in an idle
function. So, if you truly need asynchronous operations, make sure to
initialize <a href="http://library.gnome.org/devel/glib/unstable/glib-Threads.html#GThread"><span class="type">GThread</span></a>.
</p>
</div>
<div class="refsect1">
<a name="GAsyncResult.details"></a><h2>Details</h2>
<div class="refsect2">
<a name="GAsyncResult-struct"></a><h3>GAsyncResult</h3>
<pre class="programlisting">typedef struct _GAsyncResult GAsyncResult;</pre>
<p>
Holds results information for an asynchronous operation,
usually passed directly to a asynchronous <code class="function">_finish()</code> operation.
</p>
</div>
<hr>
<div class="refsect2">
<a name="GAsyncResultIface"></a><h3>struct GAsyncResultIface</h3>
<pre class="programlisting">struct GAsyncResultIface {
  GTypeInterface g_iface;

  /* Virtual Table */

  gpointer  (* get_user_data)     (GAsyncResult *res);
  GObject * (* get_source_object) (GAsyncResult *res);
};
</pre>
<p>
Interface definition for <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a> <em class="structfield"><code><a name="GAsyncResultIface.g-iface"></a>g_iface</code></em>;</span></p></td>
<td>The parent interface.</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GAsyncResultIface.get-user-data"></a>get_user_data</code></em> ()</span></p></td>
<td>Gets the user data passed to the callback.</td>
</tr>
<tr>
<td><p><span class="term"><em class="structfield"><code><a name="GAsyncResultIface.get-source-object"></a>get_source_object</code></em> ()</span></p></td>
<td>Gets the source object that issued the asynchronous operation.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="GAsyncReadyCallback"></a><h3>GAsyncReadyCallback ()</h3>
<pre class="programlisting"><span class="returnvalue">void</span>                (*GAsyncReadyCallback)              (<em class="parameter"><code><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="type">GObject</span></a> *source_object</code></em>,
                                                         <em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>,
                                                         <em class="parameter"><code><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
<p>
Type definition for a function that will be called back when an asynchronous
operation within GIO has been completed.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>source_object</code></em> :</span></p></td>
<td>the object the asynchronous operation was started with.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>res</code></em> :</span></p></td>
<td>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
<td>user data passed to the callback.</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-async-result-get-user-data"></a><h3>g_async_result_get_user_data ()</h3>
<pre class="programlisting"><a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gpointer"><span class="returnvalue">gpointer</span></a>            g_async_result_get_user_data        (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);</pre>
<p>
Gets the user data from a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>res</code></em> :</span></p></td>
<td>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>the user data for <em class="parameter"><code>res</code></em>. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2">
<a name="g-async-result-get-source-object"></a><h3>g_async_result_get_source_object ()</h3>
<pre class="programlisting"><a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject"><span class="returnvalue">GObject</span></a> *           g_async_result_get_source_object    (<em class="parameter"><code><a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a> *res</code></em>);</pre>
<p>
Gets the source object from a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>res</code></em> :</span></p></td>
<td>a <a class="link" href="GAsyncResult.html" title="GAsyncResult"><span class="type">GAsyncResult</span></a>
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
<td>a new reference to the source object for the <em class="parameter"><code>res</code></em>,
or <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if there is none. <span class="annotation">[<acronym title="Free data after the code is done."><span class="acronym">transfer full</span></acronym>]</span>
</td>
</tr>
</tbody>
</table></div>
</div>
</div>
<div class="refsect1">
<a name="GAsyncResult.see-also"></a><h2>See Also</h2>
<a class="link" href="GSimpleAsyncResult.html" title="GSimpleAsyncResult"><span class="type">GSimpleAsyncResult</span></a>
</div>
</div>
<div class="footer">
<hr>
          Generated by GTK-Doc V1.17</div>
</body>
</html>